home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / c / sozobon / sozbin15.zoo / sozdistr / doc / binary.doc / top.man < prev   
Encoding:
Text File  |  1995-09-03  |  6.0 KB  |  179 lines
  1. TOP(1)            USER COMMANDS                TOP(1)
  2.  
  3. NAME
  4.  
  5.         top   -  Tony's optimizer - The SOZOBON(X) optimizer
  6.  
  7.  
  8. SYNOPSIS
  9.  
  10.         top [options] infile [outfile]
  11.  
  12.         top [-Vh][-vgqaAbcfjlmpru] <infile> [<outfile>]
  13.  
  14.  
  15. DESCRIPTION
  16.  
  17.         Top is an assembly-code optimizer designed for use with hcc.
  18.         It accepts as input the code generated by hcc, and generates an
  19.         optimized form of the assembly as output.  By default it works as
  20.         a filter on <infile>, replacing the original code with the output. 
  21.         Using '-' as input file will cause top to read from stdin (and 
  22.         write to stdout). 
  23.  
  24.         If <outfile> is given, the optimized code is written to the named
  25.         file.  Using the name '-' for the output file causes the output to
  26.         be sent directly to stdout. 
  27.  
  28.     Diagnostic output is send to stderr.
  29.  
  30.         The optimizer is normally run by the cc command, but accepts the
  31.         following options when run manually:
  32.  
  33.         --version
  34.         -V
  35.             Print the version info to stdout and exit.
  36.  
  37.         -h      (help)
  38.             Print the commandline syntax and the options, and exit.
  39.  
  40.  
  41.         -v      (verbose)
  42.             Print some processing information (function names).
  43.             Display  statistics  about  optimizations  made  on the
  44.             file, and the short version information for 'top'.
  45.  
  46.         -g
  47.             Don't make any changes which can confuse the debugger.
  48.  
  49.         -q
  50.             Prefer generation of faster to smaller code.
  51.  
  52.         -a
  53.             Convert 'jsr' labels to PC relative if they are in this 
  54.             modulue. (Default is off, this time, but jas will do
  55.             that by default.)
  56.  
  57.         -A
  58.             Always convert 'jsr' labels to PC relative. You can use this
  59.             option if the binary is small enough, and modules are sorted,
  60.             so that the routines are to reach with short branches.
  61.         (not completely finished)
  62.  
  63.         -p
  64.             Disable peephole optimizations.
  65.  
  66.         -b
  67.             Disable conditional branch reversals.
  68.  
  69.         -f
  70.             Disable function resorting.
  71.  
  72.         -m
  73.             Disable register joining. 
  74.  
  75.         -r
  76.             Disable registerizing of variables.
  77.  
  78.         -l
  79.             Disable loop rotations. Loop rotations make the code faster,
  80.             and sometimes longer.
  81.  
  82.         -j
  83.             Disable block optimizing. Block optimizing makes the binary
  84.             shorter but not faster. To prevent making it slower use 
  85.             option '-q'.
  86.  
  87.         -u
  88.             Dont't delete link/unlink code. This feature you will need only
  89.             in functions with stack manipulations (e.g. use of alloca()).
  90.             So inhibit deleting of link/unlink in such cases.
  91.  
  92.         -c
  93.             Disable use of functions with register parameters. There are
  94.             some functions in XDlibs with different entry points, a special
  95.             one is used when the arguments are put in registers by top.
  96.  
  97.  
  98.         All this options may be included in the source code as well, by
  99.         hand, or with the '#pragma OPT "options"' statement in the C sorce
  100.         code. hcc will generate lines like:   ';opt -ra+u'    from a 
  101.         statement like:  '#pragma OPT "-ra+u"'   to pass them to top.
  102.         Unkown options will force top to exit. In verbose mode the
  103.         detected option strings are displayed.
  104.     Options switched off by commandline arguments cannot be reactivated
  105.     by '#pragma' statements.
  106.         You can prefix the options with '+' to switch them on, and
  107.         '-' to switch them off: [{+|-}vgqaAbcfjlmpru]
  108.  
  109.         There is a special statement to prevent top from optimizing a
  110.         function   ';notop'  , which is generated by hcc when detecting
  111.         a statement '#pragma -TOP'.
  112.         hcc generates some more useful lines for top and tells when
  113.         ints are long values.
  114.         
  115.  
  116.         The  optimizer  performs branch optimization  as a minimum. The
  117.         options  above  can  be  used  to  disable  everything  else. The
  118.         optimizer  will  sometimes  reverse  the sense  of a conditional
  119.         branch  to  produce  shorter  code;  this  is  disabled by the -b
  120.         options.
  121.   
  122.         Data-flow  analysis  determines  which  machine registers contain
  123.         useful  data  at any  point  in the code. This is used by other
  124.         parts  of  the optimizer, but is also a likely source of bugs.
  125.   
  126.         If  a bug is found in the optimizer, the options can be used
  127.         together to eliminate more advanced features while still gaining
  128.         the  benefit  of the  more  reliable  (and  quite useful) branch
  129.         optimizer. Sometimes the '-u' switch is really helpfull.
  130.  
  131.         The register parameter feature is used for some functions especially
  132.         changed for this. These are the string functions from std library,
  133.         and some calculation functions (long and floating point calcs).
  134.         The list of functions:
  135.  
  136.         basename()  suffix()
  137.  
  138.         bzero()     lmemcpy()   lmemmove()  memccpy()   memchr()
  139.         memcmp()    memcpy()    memicmp()   memmove()   memset()
  140.         memswap()   stradj()    strcat()    strchr()    strcpy()
  141.         strcspn()   stricmp()   stristr()   strlen()    strlwr()
  142.         strncat()   strncmp()   strncpy()   strnicmp()  strnset()
  143.         strpbrk()   strpcpy()   strpos()    strrchr()   strrev()
  144.         strrpbrk()  strrpos()   strset()    strspn()    strstr()
  145.         strtok()    strtrim()   strupr()    subnstr()   substr()
  146.  
  147.         lmul()      lmulu()     ldiv()      ldivu()     lrem()
  148.         lremu()
  149.  
  150.         fpmul()     fpdiv()     fpadd()     fpsub()     fpcmp()
  151.         fpneg()     fpltof()    fpftol()
  152.  
  153.  
  154. ENVIRONMENT
  155.  
  156.         If $STDERR is set, stderr file handle is 2, else it is -1
  157.     (console device)
  158.  
  159.  
  160. COPYRIGHT
  161.  
  162.         top V 2.00X is part of the SOZOBONX C compiler.
  163.  
  164.         V2.00 Copyright (c) 1988-1992 by Sozobon, Ltd.
  165.         for eXtended Version by C. Wempe & H. Weets
  166.         and by J Geiger (1992-1994)
  167.  
  168. BUGS
  169.  
  170.     Please report to 
  171.         MausNet: Volker Seebode @ AC3
  172.         Internet: seebode@plesnik.bonsai.de
  173.     using 'bugform.doc' from the SozobonX distrib.
  174.         
  175. SEE ALSO
  176.  
  177.         cc(1), hcc(1)
  178.  
  179.